
//Copyright 1997-2009 Syrinx Development, Inc.
//This file is part of the Syrinx Web Application Framework (SWAF).
// == BEGIN LICENSE ==
//
// Licensed under the terms of any of the following licenses at your
// choice:
//
//  - GNU General Public License Version 3 or later (the "GPL")
//    http://www.gnu.org/licenses/gpl.html
//
//  - GNU Lesser General Public License Version 3 or later (the "LGPL")
//    http://www.gnu.org/licenses/lgpl.html
//
//  - Mozilla Public License Version 1.1 or later (the "MPL")
//    http://www.mozilla.org/MPL/MPL-1.1.html
//
// == END LICENSE ==
using System;
using System.Collections;

namespace Swaf.Gui
{
	public enum CommandChangeType {Enabled, DisplayInfo};
	public enum CommandMode {Normal, Highlighted, Selected};

	/// <summary>Used by <c>IAction</c> for its <c>OnActionChange</c> event.</summary>
	public delegate void CommandChanged(object sender, CommandChangeType type);

	/// <summary>Represents a gui command that can be given to some object that can trigger the
	/// command from something such as user input or timers.</summary>
	/// <remarks>
	/// Typically, some GUI element will display a graphical representation of this command that
	/// allows the user to trigger the command either as a highlight or a selection.  However, 
	/// commands don't necessarily have to be triggered via a graphical element.  Hot keys and
	/// timers could also trigger commands.
	/// <p>The <see cref="System.Framework.Gui.ActionCommand">ActionCommand</see> class implements
	/// this interface by mapping onto an an <c>IAction</c>.</p>
	/// </remarks>
	public interface ICommand
	{
		/// <summary>
		/// Indicates wether this command is just a simple seperator or an actual command.
		/// </summary>
		/// <remarks>When this is true, all other properties and methods are non-functional.  This
		/// option helps command list display widgets to place menu seperators in itself.</remarks>
		bool IsSeperator{get;}

		/// <summary>When a command has children that represent the command itself, this should be true, 
		/// otherwise this should be false.</summary>
		/// <remarks>If a command has no children, this property is meaningless.  When a command
		/// has child commands, this property indicates weather this command is a command with children
		/// or just a "child list" initself.  When applied to a command list display, this should indicate 
		/// wether:
		/// True - The children of this command are displayed in the same tree level as 
		/// this command's siblings.  This the command is just a "child list" and the children act
		/// together as standins for this command object.
		/// False - This command is displayed in the same tree level as its siblings, but
		/// is also represented as a sub-menu option with its child commands being displayed in the
		/// popup sub menu. </remarks>
		bool UseChildenAsStandins{get;}

		/// <summary>This event is triggered when either the <c>Enabled</c> property changes or the
		/// Text/Image content has changed.</summary>
		event CommandChanged OnChange;

		/// <summary>
		/// Registers the callbackObj to be called when the command is triggered either during a
		/// highlight or selection.
		/// </summary>
		/// <remarks>Rather then using a normal deligate, this method uses the more flexible 
		/// reflection mechanism so that is can attem to call the method specified with the
		/// command param or not depending on wether the given command has a param.</remarks>
		/// <param name="mode">The mode to register for.  The CommandMode.Normal is not allowed
		/// and if specified will generate an exception.</param>
		/// <param name="callbackObj">The object is use reflection to to call back as the command is
		/// triggered.</param>
		/// <param name="methodName">The name of the mothod to call on the callbackObj object.  This
		/// method can either take no parameters or take one parameter that will be the command
		/// param if it has one.</param>
		void registerTrigger(CommandMode mode, object callbackObj, string methodName);

		/// <summary>The text to display to the user for the command.</summary>
		string getText(CommandMode mode);

		/// <summary>The location of the image to display to the user for the command.</summary>
		Uri getImageUrl(CommandMode mode);

		/// <summary>Child commands for the command</summary>
		/// <remarks>Commands can have child commands, which can build trees of commands.
		/// A display of a command with children might display popup menus or sub menus
		/// for the child commands.  This value should never be null.  If a command doesnt
		/// have child commands then this should return a list with zero elements in it.</remarks>
		IList Children {get;}

		/// <summary>The enabled state of the command.  Commands that are <c>Enabled == false</c>
		/// shouldnt have highlight or selection triggers do anything.</summary>
		bool Enabled{get;set;}

		/// <summary>Triggers the command's highlight processing.</summary>
		void triggerHighlight();

		/// <summary>Triggers the command's selection processing.</summary>
		void triggerSelection();
	}
}
